home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / kabc / vcardconverter.h < prev    next >
Encoding:
C/C++ Source or Header  |  2008-02-13  |  4.3 KB  |  164 lines
  1. /*
  2.     This file is part of libkabc.
  3.     Copyright (c) 2002 Tobias Koenig <tokoe@kde.org>
  4.  
  5.     This library is free software; you can redistribute it and/or
  6.     modify it under the terms of the GNU Library General Public
  7.     License as published by the Free Software Foundation; either
  8.     version 2 of the License, or (at your option) any later version.
  9.  
  10.     This library is distributed in the hope that it will be useful,
  11.     but WITHOUT ANY WARRANTY; without even the implied warranty of
  12.     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13.     Library General Public License for more details.
  14.  
  15.     You should have received a copy of the GNU Library General Public License
  16.     along with this library; see the file COPYING.LIB.  If not, write to
  17.     the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  18.     Boston, MA 02110-1301, USA.
  19. */
  20.  
  21. #ifndef KABC_VCARDCONVERTER_H
  22. #define KABC_VCARDCONVERTER_H
  23.  
  24. #include <qstring.h>
  25.  
  26. #include "addressee.h"
  27.  
  28. namespace KABC {
  29.  
  30. /**
  31.   @short Class to converting contact objects into vCard format and vice versa.
  32.   
  33.   This class implements reading and writing of contact using from/to the
  34.   vCard format. Currently vCard version 2.1 and 3.0 is supported.
  35.  
  36.   Example:
  37.  
  38.   \code
  39.  
  40.   QFile file( "myfile.vcf" );
  41.   file.open( IO_ReadOnly );
  42.   
  43.   QString data = file.readAll();
  44.  
  45.   VCardConverter converter;
  46.   Addressee::List list = converter.parseVCards( data );
  47.  
  48.   // print formatted name of first contact
  49.   qDebug( "name=%s", list[ 0 ].formattedName().latin1() );
  50.  
  51.   \endcode
  52. */
  53. class KABC_EXPORT VCardConverter
  54. {
  55.   public:
  56.  
  57.   /**
  58.     @li v2_1 - VCard format version 2.1
  59.     @li v3_0 - VCard format version 3.0
  60.    */
  61.    enum Version
  62.     {
  63.       v2_1,
  64.       v3_0
  65.     };
  66.  
  67.     /**
  68.       Constructor.
  69.      */
  70.     VCardConverter();
  71.  
  72.     /**
  73.       Destructor.
  74.      */
  75.     ~VCardConverter();
  76.   
  77.     /**
  78.       Creates a string in vCard format which contains the given
  79.       contact.
  80.  
  81.       @param addr The contact object
  82.       @param version The version of the generated vCard format
  83.      */
  84.     QString createVCard( const Addressee &addr, Version version = v3_0 );
  85.  
  86.     /**
  87.       Creates a string in vCard format which contains the given
  88.       list of contact.
  89.  
  90.       @param list The list of contact objects
  91.       @param version The version of the generated vCard format
  92.      */
  93.     // FIXME: Add error handling
  94.     QString createVCards( Addressee::List list, Version version = v3_0 );
  95.  
  96.     // FIXME: Add "createVCards( AddressBook * )"
  97.  
  98.     /**
  99.       Parses a string in vCard format and returns the first contact.
  100.      */
  101.     Addressee parseVCard( const QString& vcard );
  102.  
  103.     /**
  104.       Parses a string in vCard format and returns a list of contact objects.
  105.      */
  106.     // FIXME: Add error handling
  107.     Addressee::List parseVCards( const QString& vcard );
  108.  
  109.     // FIXME: Add "bool parseVCards( AddressBook *, const QString &vcard )"
  110.  
  111.     /**
  112.       @deprecated
  113.      */
  114.     bool vCardToAddressee( const QString&, Addressee &, Version version = v3_0 ) KDE_DEPRECATED;
  115.  
  116.     /**
  117.       @deprecated
  118.      */
  119.     bool addresseeToVCard( const Addressee&, QString&, Version version = v3_0 ) KDE_DEPRECATED;
  120.  
  121.   private:
  122.     /**
  123.       Split a string and replaces escaped separators on the fly with
  124.       unescaped ones.
  125.      */
  126.     QStringList splitString( const QChar &sep, const QString &value );
  127.  
  128.     struct VCardConverterData;
  129.     VCardConverterData *d;
  130. };
  131.  
  132.  
  133. /**
  134.     Helper functions
  135.   */
  136.  
  137. /**
  138.   * Converts a QDateTime to a date string as it is used in VCard and LDIF files.
  139.   * The return value is in the form "yyyyMMddThhmmssZ" (e.g. "20031201T120000Z")
  140.   * @param dateTime date and time to be converted 
  141.   * @since 3.2
  142.   */
  143. KABC_EXPORT QString dateToVCardString( const QDateTime &dateTime );
  144.  
  145. /**
  146.   * Converts a QDate to a short date string as it is used in VCard and LDIF files.
  147.   * The return value is in the form "yyyyMMdd" (e.g. "20031201")
  148.   * @param date date to be converted 
  149.   * @since 3.2
  150.   */
  151. KABC_EXPORT QString dateToVCardString( const QDate &date );
  152.  
  153. /**
  154.   * Converts a date string as it is used in VCard and LDIF files to a QDateTime value.
  155.   * If the date string does not contain a time value, it will be returned as 00:00:00.
  156.   * (e.g. "20031201T120000" will return a QDateTime for 2003-12-01 at 12:00)
  157.   * @param dateString string representing the date and time.
  158.   * @since 3.2
  159.   */
  160. KABC_EXPORT QDateTime VCardStringToDate( const QString &dateString );
  161.  
  162. }
  163. #endif
  164.